Skip to content

spec(FIX-1906): coding runs for mapped projects work in worktrees of your checkout - #3177

Merged
jhoffner merged 3 commits into
mainfrom
claude/project-thread-wefsi0
Oct 12, 2026
Merged

jhoffner merged 3 commits into
mainfrom
claude/project-thread-wefsi0

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 12, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

Retained spec for FIX-1906, under epic FIX-1903. Start at specs/issues/FIX-1906/SPEC.md.

Before: a project's coding run gets a branch in a hidden clone that the host made. A local repository can't keep the project's files beside the worktree, and nothing ties a project to a person's checkout.

After: the operator's config names a checkout and the shared projects it serves, each identified by its organization and id. A run on one of those projects gets a fresh worktree of that checkout. Its branch lives there, and the project's files sit in project/ beside the worktree. Some projects never get a worktree of the checkout: one the config doesn't name, a project with the same id in another organization, and any private project.

The kill line is cleared. A fresh worktree of this monorepo installs offline from the machine's shared pnpm store in 6 s, and builds every package in 86 s. That build cost is paid once per change, because turbo's cache is shared across worktrees. Its tests pass. The proof can be re-run from poc/kill-line/check.sh.

How: the mapping is an option of workforce's projectWorkspace() (D1). It is matched against the stored row and the run's server-set organization. The host can't hold the mapping, because it only sees a bare id. The epic coordinator accepted this as a stricter reading of ER-13. Workspace's local-repository mode learns to keep files beside the checkout. A settled run's branch stays checked out, and continuing the run is proved on the mapped path (D3). Two projects on one checkout are tested with a control that must fail.

What's asked of you

The direction only. D1 to D3 are engineering calls, and there is no open question for the owner. Merging this PR is the approval, and implementation starts when it merges.

🤖 Generated with Claude Code

https://claude.ai/code/session_013uVA1pkZu3CXS5ZeEP8xNo

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013uVA1pkZu3CXS5ZeEP8xNo
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013uVA1pkZu3CXS5ZeEP8xNo
@linear-code

linear-code Bot commented Oct 12, 2026

Copy link
Copy Markdown

FIX-1906

@jhoffner jhoffner self-assigned this Oct 12, 2026
@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-12T18:50:34.405488Z 5daab6d Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Copy link
Copy Markdown
Collaborator Author

Second-look + architecture review (direction check, not a rewrite)

Read SPEC, DECISIONS, BUSINESS-RULES, PLAN and the POC against project-workspace.ts, local-host.ts and worktree.ts. The direction holds. D1 (mapping lives in projectWorkspace(), bound to visibility + id) is the right place: the host only sees a bare projectId, and the source already reads the row at its visibility. S2 (kept files beside a local checkout) is the only host change and is needed. I found no leaner shape that still meets the goal. Findings below are ordered by how much they should change the implementer's plan.

1. Worktrees and branches in the operator's checkout have no lifecycle (worth a rule)

D3 makes every settled run's worktree and branch permanent, and BR-13 to BR-15 say what happens when a person removes one. Nothing says who removes them or what accumulates. Every mapped run adds a .git/worktrees/* entry and a branch to a checkout the person uses daily. After a few dozen runs, git branch and git worktree list in their own repo are noise. Suggest the implementer add one BR that says the honest thing, even if it is "the server never removes them; the operator prunes; here's the one-liner" in DOCS.md. If a reaper is out of scope, name it in Follow-ups so it isn't discovered in production. Don't build it in this PR.

2. D3's rejected alternative is the weaker one

D3 rejects "detach HEAD on settle". The more natural alternative is not rejected anywhere: remove the worktree on settle and keep the branch. BR-14 already proves the host re-adds a worktree on an existing branch, and a held-work store exists for uncommitted files. That would leave the branch free to git checkout in the person's own tree, which is the cost D3 admits to. It may still lose (uncommitted work, and "review in the worktree"), but the spec should say why, since the decision is currently argued against a straw option. Note, not a blocker; D3 is low-regret either way.

3. D1's double-naming has an unguarded mismatch

The checkout is named in checkouts and in localRepositories. BR-5 catches a path missing from the host list, but only at run time. Also nothing checks that the checkout's own origin matches the entry's remote. A typo pairing remote A with repo B puts project A's agent in repo B. gitIdentity() already exists in worktree.ts. Cheapest fix in scope: make the BR-5 refusal name both option names so the operator sees the pairing. A remote-vs-origin check is optional; I would skip it unless it's a few lines.

4. The epic's retained spec now contradicts this one

Epic D3 and ER-9 say the workspace host gains the mapping. D1 puts it in projectWorkspace() and says "no epic amendment". Per CLAUDE.md §6, two retained docs that disagree shouldn't both stand. Add a one-line erratum in the epic's DECISIONS (or amend D3's wording) in this PR or the next. Related: PLAN "At implement time" still says "If the epic coordinator rules otherwise, stop and re-gate", but the PR body and Follow-ups say it is already accepted. Drop the stale line.

5. Weight versus what is asked

The PR says there is no open question for the owner, yet it ships 12 files / about 1,100 lines, with four SVG figures for three decisions it calls engineering calls. D2 and D3 read as "decided, not asked" items. Not a blocker, but if the figures are the cost-driver for reviewers, D2 and D3 could drop theirs and keep the one-line "it comes down to" sentence.

6. Implementation notes (no spec change)

  • S2 removes a refusal and inverts its test. Make sure the "no kept files, place is the checkout" path keeps marker and lock bytes identical (BP-030); V2 should assert on an existing on-disk place, not just a fresh one.
  • The goal check writes into a developer's real checkout. The guardrail to clean up on failure is right; also make it refuse to run if the checkout has a dirty worktree it did not create, so the cleanup can't touch someone's work.
  • mergeable_state is unstable; check which CI check is red before merge.

No changes needed to the D1 fence or the S1/S2 split.


Generated by Claude Code

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify review (FIX-1906 spec)

Verdict: Approve direction. The core design is the right trade for BP-031 and continuation semantics; complexity is mostly in surface area (docs, epic alignment, operator config), not in the worktree model itself.

What looks like the right approach

  • D1 (mapping on projectWorkspace(), full address) is the simpler correct design vs a host option keyed on bare projectId. The private-twin case is real (projectAddressSchema), and pushing visibility into the source matches how answers are already formed.
  • D2 (agent install + shared pnpm store) avoids the silent “tests import the checkout” failure mode from linked node_modules. The kill-line POC (poc/kill-line/) is appropriate retained evidence for a spec that gates the epic.
  • D3 (branch stays checked out) follows from existing harness-manager continuation goals; detaching would be a larger behavioral change.
  • Implementation plan (S1–S2) reuses existing shapes: remote runs already use checkout/ + project/; local mapped runs generalize that instead of inventing a parallel layout. No need for simple-git — extend worktree.ts / exec.ts and existing local-host-* tests.

Where the approach went further than necessary (optional trims)

  1. Epic text vs D1 without an epic amendment — FIX-1903 D3/ER-9 still read as “the workspace host gains that mapping.” EVOLUTION records coordinator acceptance as a “stricter reading.” That works procedurally (ER-17), but it leaves two canonical stories. Simpler: a small follow-up epic amend (one paragraph in D3 + ER-9: mapping lives on projectWorkspace, host allowlist unchanged) so implementers and FIX-1904’s profile author aren’t reconciling cross-links.
  2. Operator config names the checkout twice (localRepositories + checkouts[].checkout) — acknowledged in D1. Simpler (if you want less foot-gun): document that FIX-1904’s host wiring should derive the allowlist from unique checkouts[].checkout values, or validate equality at boot and refuse on mismatch (beyond BR-5’s path-not-listed case).
  3. Spec volume — 20 BRs, three decision SVGs, fence mermaid in both SPEC and BUSINESS-RULES, plus DECISIONS “Settled” repeating the POC table. The contract could live in ~12 BRs + PLAN guardrails; figures could be mermaid-only unless you need SVG for the spec site.
  4. Goal check signal — leg a bundles in-checkout, offline install, build, branch, and note-saved. The kill line is already proved in the POC; the goal could assert mapping + one install/build smoke and leave note-saved to workforce/workspace unit tests (still required by BR-11). Optional, not blocking.
  5. POC F3 (36 concurrent worktrees) is stronger than V3 needs (two projects × 10). Fine as spike evidence; don’t feel obliged to imply CI must reproduce 36-way stress.

Alternatives considered (and why I’d still stay on this PR)

Alternative Why it’s tempting Why this spec still wins
Host-side mapping once source carries full address One config surface, matches epic wording Needs a trusted address on every RunSource answer first; workforce-only option is smaller now
Fold FIX-1906 into FIX-1904 One PR for “dev Lab works” Epic D1 explicitly keeps kill-line + host capability separate; risk isolation is real
Host runs pnpm install after provision Agents might skip install D2’s flip is documented; 6s on warm store is cheap vs wrong imports
Require only checkouts (drop duplicate path) Less config localRepositories is the existing security allowlist; dropping it is a wider API change

Merge hygiene (not a design block)

The GitHub diff against 982524… shows deleting FIX-1185 because this branch forks before #3166 landed on main. A rebase onto current main before merge should make the PR diff “add FIX-1906 only.” Worth doing so reviewers don’t think FIX-1185 is being reverted.

Performance / ops (spec-level)

Cold pnpm store and cold turbo cache are the real costs; the spec documents them. Turbo sharing across worktrees is a good finding — worth keeping the “re-run POC after pnpm/turbo bump” line in PLAN.


Happy to see implementation follow existing test harnesses (local-host-repo.spec.ts, project-workspace-task.test.ts, goals/devforce-lab/it-codes-in-the-projects-repository) rather than new frameworks.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-1906/SPEC.md Resolved
Comment thread specs/issues/FIX-1906/EVOLUTION.md Resolved
Comment thread specs/issues/FIX-1906/PLAN.md Resolved
Comment thread specs/issues/FIX-1906/DECISIONS.md Resolved
Comment thread specs/issues/FIX-1906/SPEC.md Resolved
Comment thread specs/issues/FIX-1906/BUSINESS-RULES.md Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5daab6d084

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread specs/issues/FIX-1906/PLAN.md Resolved
Comment thread specs/issues/FIX-1906/PLAN.md Resolved
Comment thread specs/issues/FIX-1906/PLAN.md Resolved
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013uVA1pkZu3CXS5ZeEP8xNo
jhoffner pushed a commit that referenced this pull request Oct 12, 2026
FIX-1906 round 1 (#3177, 0c42dfd) keys `checkouts[].projects` on
`{ orgId, id, tenantId? }` for shared projects only. The profile's entries
now name the Lab's `LAB_ORG_ID` (teams/devteam/host.mts), and
`localRepositories` is derived from the `checkouts` paths. BR-14 names an
org-less or other-org session as a miss, refused by name under D3.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JdyQCD5rESK6t4xABFzRZk
@vercel

vercel Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 12, 2026 7:27pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 12, 2026 7:27pm UTC
flow-state-dev-ui Ignored Ignored Oct 12, 2026 7:27pm UTC

Request Review

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@claude is this design config time only or does it work with data driven cases where we can change a project's settings through the interface?

Copy link
Copy Markdown
Collaborator Author

from: fsd-claude
session: fix-1906
kind: reply

Which projects can use your checkout is set in config only, read when the server starts. The rest of a project stays data-driven.

  • Changeable through the interface, as today: the project's repository, its brief, and its members. Changing the repository to something other than the mapped remote takes the project off your checkout immediately. Its runs then get a fresh clone again.
  • Config only: granting a project access to your checkout. That was deliberate (epic ER-13). The checkout holds your unpushed work and refs, and project rows are written by users and agents. If editing a project in the interface could grant this access, anyone who can edit a project could get a worktree of your machine's repository.

If you want to grant it from the interface later, the safe version is an operator-only setting stored on the host's side, not on the project row. Only the server's operator could change it, and it would take effect without a restart. That is a small follow-up on top of this spec and changes nothing in it. The dev profile doesn't need it, because its two projects are fixed. I'd leave it out of this epic and file it if you want it.


Generated by Claude Code

@jhoffner
jhoffner merged commit 59e2d16 into main Oct 12, 2026
19 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants